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LQ.t r .ari.yj c t*g r» 

Welcome to the Programmers' Tool ICit. Thi* diskette contains routines 
written in ACTION! which extend your ACTION! programming capabilities. 
The following is a list of the files on the disk, together with a short 
description of what each file does. 

ABS.ACT - a routine which will return the absolute value of an INT. 

ALLOCATE.ACT - routines which allow dynamic runtime memory 
manipulation. 

CHARTEST.ACT - routines which perform various tests and functions 
on characters. 

C1RCLE.ACT - a circle drawing routine using neither Sine nor Cosine. 

CONSOIE.ACT - a routine which both debounces the console Keys and 
allows you to tie routines into them. 

IO.ACT - routines which implement some advanced I/O operations. 
JOYSTIX.ACT - routines which maKe interpreting joysticK input easier. 
PMO.ACT - player/missile graphics routines. 

PRINTF.ACT - an extended Version of the ACTION! Library 'PrintF'. 

REAL.ACT - routines which allow you to use floating point numbers. 

SORT.ACT - QuicKSort for BYTE, CARD, INT, and string data. 

TURTLE.ACT - an implementation of turtle graphics, ala LOGO. 

GEH.DEM - a four person game written in ACTION!. 

KALSCOPE.DEM - a colorful demo of ACTION!'s speed. 

HUSIC.DEH - a demo which creates a playable organ. 

SNAILS.DEM - a two person game translated from BASIC to ACTION!. 

WARP.DEM - a one person game which uses many of the advanced 
constructs and abilities of ACTION!. 

There are also some files with the extension '.DMn'» where 'n' is a number. 
These are demos of the routines in a specific file, designed to help you 
better understand the procedure required to maKe use of the Tool Kit 
routines. 
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Mot»; In most of the ACTION! source files there »re global variables 
and procedures which contain the underline character These 

variables and routines are internal to the Toolkit routines, and should be 
neither called nor accessed by you unless you are positive you know for 
what they are used. 


To Boot This Disk simply boot your DOS disk with the ACTION! cartridge 
mserted, and then put this disk in your drive. THIS DISKETTE DOES 
NOT HA VE DOS ON IT AND WILL NOT BOOT DIRECTLY. 



Purpose: To return the absolute value of an INTeger. 

Params: n - the INTeger whose absolute value is returned. 

Description: This function will return the absolute value of the INT 
passed to it. 


The routines in this file allow you to allocate and free blocks of memory at 
runtime. If you want to use this capability. you must first call the 
Alloclnit routine. Alloclnit expects a global CARD variable called SndProg 
to contain the address of the end of your program. To do this. compile 
your program, and then type the following in the Honitor immediately after 
compiling: 

SET EndProg«*« [RETURN! 

Now you can run your program. 

Technical Note: The Alloc and Free routines operate on a 'free list'. This 
list gives the location and size of every free memory block. Alloc simply 
removes a block from the free list. and Free puts a block back into the list. 


Purpose: To set up the free list and initialize the allocation routines. 

Params: p - the address of the first free memory location in memory. 

Description: This routine is used to create the free list so that 
Alloc and Free may be used. See the introduction to this section for 
instructions on its use. 

Note: If you are planning to use P/M graphics and/or bit-map graphics. 
you should enable the P/Ms and be in the most memory intensive 
graphics mode you plan to use when you call Alloclnit. since it 
considers all memory up to MEMHI <$2E3> to be free space. 
(Alternatively, you can merely change the value of MEMHI.) 



IC 


Purpose: To allocate a block of memory of a specified size, returning 
the addres* of that block. 

Param*: nBytes - the size in bytes of the block to be allocated. 

Description: This routine allows you to reserve a block of memory 
'nBytes' long. The starting address of the block is returned. so, for 
example, you could use it to allocate space for a large array at 
runtime, after you've determined the size array you need: 

PROC TestO 
CARD size 

BYTE ARRAY bigarray 

PrintCSize of Array>> *) 
size*InputC(> 
bigarray=Alloc(size) 

RETURN 

Note: the smallest block you can allocate is 3 bytes. 




Purpose: To free a block of memory which has previously been reserved 
using the Alloc function. 

Params: target - the starting address of the block to free. 

nBytes - the length in bytes of the block to free. 

Description: This procedure allows you to return a block of memory 
used by Alloc to the free list. 


PROC PrintFreeListO 

Purpose: To print out the free list. 

Params: none 

Description: This procedure will print out the current free list, and 
should be used mostly for diagnostic debugging reasons. 


The routines in this file are 

IsAlpha - a 
IsUpper - a 
IsLower - a 
IsDigit - a 
ToUpper - a 
ToLower - a 


very diverse, induding: 

character test 
character test 
character test 
character test 
character manipulation 
character manipulation 


BYTE FUNC IsAlphaiBYTE c) 

Purpose: To test a single character to see if it is a letter. 

Params: c - the character to be tested. 

Description: This function checks c to see if it is an alphabetic 
character. If it is, a 1 is returned; otherwise a 0 is returned. 



Purpose: To test a single character to see if it is an uppercase letter. 


Params: c - the character to be tested. 


Description: This function checks c to see if it is an uppercase 
alphabetic character. If it is, a 1 is returned; otherwise a 0 is 
returned. 


BYTE FUNC IsloweriBYTE c) 

Purpose: To test a single character to see if it is a lowercase letter. 


Params: c - the character to be tested. 


Description: This function checks c to see if it is a lowercase 
alphabetic character. If it is, a 1 is returned; otherwise a 0 is 
returned. 
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Purpos*: To test a single character to see if it is a digit. 


Params: c - the character to be tested. 


Description: This function checks c to see if it is a digit (0 - 9). If it 
is, a 1 is returned; otherwise a 0 is returned. 



Purpos#: To change lowerease letters to uppercase. 


Params: c - the character to put into uppercase. 


Description: This function will return the uppercase of the character 
passed to it. If the character is already uppercase, or is not 
alphabetic, then the character is returned unchanged. 



Purpose: To Change uppercase letters to lowerease. 


Params: c - the character to put into lowerease. 


Description: This function will return the lowerease of the character 
passed to it. If the character is already lowerease, or is not 
alphabetic, then the character is returned unchanged. 


AC] ON! ToolKit ver !.»• 


Pag* 7 



The circle drawing routine in this fil* is somewhat special, sine* it dots 
not need to compute Sine or Cosine« and so is very fast. One caveat, 
however, this routine does no sereen bounds checking, so either make sure 
your circle will fit on the sereen, or add your own bounds checking. 


Purpos*: To draw a circle of specified center, radius, and color. 

Params: x - the horizontal position of the center of the circle to b* 
drawn. 

y - the vertical position of the center of the circle to be 
drawn. 

r - the radius of the circle, 
c - the color of the circle. 


Description: This procedur* allows you to draw a circle of specified 
center, radius, and color. The System variable color is set to c, so c 
should not be the actual color number as used in the 
SetColor procedure, but rather the 'color' value in the current graphics 
mode which corresponds to the SetColor register which contains the 
color you want to use. 
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CO N SOLE .ACT 

The routine* in this -fil* allow you io hooK the execution of a specific 
routine to the pressing of one of the console keys (START, SELECT, 
OPTION). Before you use this capability you must call the 
InitConsole procedure as follows: 

In i tConsol eO 

Once you have done this you need simply equate the address of your 
routine to one of the console keys. You can do this in the following 
manner: 

1 - write your routine (it can have no parameters). 

2 - call the InitConsole procedure. 

3 - equate the name of the console Key you wish to your routine. 

The following example should help darify this procedure: 

INCLUDE ‘CONSOLE.ACT" 

PROC DoStart«) 

PrintE«’START Pressed*) 

RETURN 

PROC DoSelectO 
PrintE«’SELECT Pressed’) 

RETURN 

PROC DoOption«) 

PrintECOPTION Pressed’) 

RETURN 


PROC MainO 
Ini tConsoleO 
Start^DoStart 
Select*DoSelect 
Option=D60ption 
DO OD 
RETURN 


jset up console handler 
;DoStart when START 
;DoSelect when SELECT 
;DoOption when OPTION 


IO.ACT 


The routines in this file allow you to do advanced disk file manipulation 
front an ACTION! program. Operation* implemented are: 

Rename a file Poriaat a dlskett* 

Erase a file Block ßet of data fron disk 

Protect a file Block Put of data to disk 

Unprotect a file 

Not*: The first four of the above Operation* (those involving a disk fil*) 
require that the file name have the 'Dn:' (n*l-8) device specifier 
prepended to the actual file name; otherwise you will get a 'Nonexistent 
Device' error. 


PROC RenametBYTB ARRAY filename) 

Purpose: To rename a disk file. 

Params: filename - the old and new file names. 

Description: This routine will rename the specified disk file, and 
should be used as follows: 

Rename«’DlsTEMPl.ACT TEMP.ACT’) 

This example will rename TEMP1.ACT on drive 1 to TEMP.ACT. Notice 
that the new name follows the old name in the file name string, with 
only a space or comma separating the two. Note that the new name may 
NOT have a device specifier. 


PROC Erase(BYTE ARRAY filename) 

Purpose: To erase a disk file. 

Params: filename - the file to erase. 

Description: This procedure will erase a disk file and should be used 
as follows: 

Erase«’D2:JUNK.ACT’) 

This example will erase JUNK.ACT on drive 2. 
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PROC Protect(BVT8 ARRAY filename) 

Purpos»: To prot*ct a disk file. 

Params: filename - thc file to protect. 

Description: This will protect a disk file, and should be used as 
follows: 

ProtectfDs*.**) 

This example will protect all files on drive 1. 


PROC BPutiBYTE chan CARD addr,len) 

Purpos»: To writ» a block of binary or text data to a specified d*vic*. 

Params: chan - the channel. 

addr - the address from which to get the data, 
len - the number of bytes of data. 

Description: This procedure allows you to writ» a block of data, and is 
the complement to BGet. 


PROC UnProtect (BYTE ARRAY filename) 

Purpose: To unprotect a disk file. 

Params: filename - the file to unprotect. 

Description: This procedure will unprotect a file which has been 
protected using either the Protect routine above, or the DOS XL 
PRO command. It is used in the same way as Protect above. 


PROC FormatiBYTE ARRAY DriveSoec) 

Purpose: To format a diskette. 

Params: DriveSpec - the drive containing the disk to be initialized. 

Description: This routine allows you to initialize disks, and should be 
used as follows: 

Format<*D2j*) 

This exampl» will format whatever disk is in drive 2 (unless of course 
it has a write protect tab on it). 


CARD FUHC BOetiBYTE chan CARD addr.len) 

Purpose: To read a block of binary or text data from a specified 
device. 

Params: chan - the channel. 

addr - the address at which to put the data, 
len - the number of bytes of data. 

Description: This function allows you to read a block of data, 
returning the actual number of data bytes read (this will be different 
from len if End-Of-File was reached before 'len' bytes were read). 
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JOYSTIX.ACT 
INT FUNC HSticKtBVTg porl) 

Purpose - - To return the horizontal reading of a specified joysticK. 

Params: port - the port of the Joystick whose horizontal reading is 

desired. 

Description: This routine reads the value of a joysticK and returns the 
tollowing values: 

-1 - horizontal movement left 
0 - no horizontal movement 
1 - horizontal movement right 

This routine is much easier to use than the Stick tunction in the 
ACTION! Library. 


INT FUNC VStlcktBYTE Port) 

1 

Purpose: To return the vertical reading ot a specitied joystick. 

Params: port - the port ot the joystick whose vertical reading is 
desired. 

Description: This routine reads the value ot a joystick and returns the 
tollowing values: 

-1 - vertical movement up 
0 - no vertical movement 
1 - vertical movement down 

l 

This routine is much easier to use than the Stick tunction in the 
ACTION! Library. 
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PMO.ACT 


Th* routines in this tile allow you easy implementation of the ATARl's 
player/missil* Ihereafter called P/M's) graphies capabilities. To giv* you 
a sense of the extent of this implementation, we'll giv* a quick synopsis 
of the routines betöre going into them in detail: 


PHGraphics 

PMSetColor 

PHAdr 

PMClear 

PMMove 

PHCreate 

PMHit 

PMHi tClr 

PMHPos 

PMVPos 

Graphics 


- Set up P/M graphies 

- Set a P/M's color 

- Give the address of a P/M 

- Erase a P/M 

- Move a P/M 

- Create a P/M 

- Test the P/M collision registers 

- Reset the collision registers 

- Horzontal positions of P/Ms 

- Vertical positions of P/Ms 

- A roodified Graphics 


Introductory Notes: In several of the routines in this section you will se* 
the parameter num, referring to the number of the player/missile. This 
number is assigned values as follows: 


0 - player 0 

1 - player 1 

2 - player 2 

3 - player 3 


4 - missiI* 0 

5 - missi1e 1 

6 - missi1e 2 

7 - missile 3 


In some cases only the values 0-3 will be valid or make sense. 


PRDC PHGraphics (BYTE mode) 

Purpose: To turn P/M graphies on or off. 

Params: mode - determines v/hich P/M mode. 

Description: This procedure is very much like the Graphics routine in 
the ACTION! Library, except that this one Controls player/missile 
graphies. The mode values are as follows: 

0 - turn off P/Ms 

1 - single line resolution P/Ms 

2 - double line resolution P/Ms 

Not*: This procedure moves all the players and missiles off the 
screen, but does not erase the P/M memory. To erase it, use PMClear. 
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PROC PMSetColor(BVTE num.hue.lum) 

Purpose: To set the hue and luminance of a player and its associated 
missile. 


Params: num - the player number (0-3). 

hue - the hue for the player. 
lum - the luminance for the player. 

Description: This procedure is very much like the SetColor Library 
routine. In fact the colors corresoonding to hue and lum are exactly as 
shD7.fi in the ACTION! manual under SetColor. The difference is that it 
allows you to set the color of a P/M, not a playfield. 


CARD F'JNC PMAdr(BYTE num) 


Purpose: To return the address of a given P/M's memory block. 
Params: num - the P/M number. 


Description: This function returns the starting address of the memory 
block allotted to the P/M specified by r,um. Since the missiles all 
cccupy the same block of memory, num values 4-7 will ali return the 
same address. 


PROC PMClearlBYTE num) 


Purpose: To dear out the memory block of a specified P/M. 
Params: num - the P/M number. 


Description: This procedure zeroes all the bytes in the memory block 
of the P/M given by num. If it is a missile, only tnat part of the block 
allotted to the missile will be zeroed. 


PROC PMHovelBYTE num.x.v) 


Purpose: To move a specified P/M 


Params: num - the P/M number. 

x - horizontal Position to which to move the P/M. 
y - vertical Position to which to move the P/M. 


Description:This procedure allows you to move P/Ms easily and quickly. 
You simply need to specify the P/M number and the x,y Position to 
which you want it moved. 
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Purpose: To allow easy creation of a P/M. 


Params: num - the P/M number. 

pm - the array which contains the P/M's shape data, 
len - the length of the array pm. 
width - the width of the player. 
x - the starting horizontal Position of the P/M. 
y - the starting vertical position of the P/M. 

Description: This routine allows you to create a P/M. You need to 
pass it the P/M number, the name of the array which contains its 
shape, the length of that array,the P/M's width <l=single, 2=double, 
4=quadruple), and the starting x,y position of the P/M. 


BYTE FUNC PMHitlBYTB num.cnum) 

Purpose: To determine whether a specified P/M has collided with a 
specified player or playfield. 


Params: num - the P/M number. 

cnum - the player or playfield to test for a collision. 

Description: This function allows you to see if a given P/M has 
collided with a specified player or playfield, returning a 1 if there is a 
collision, a 0 otherwise. The num values are described in the beginning 
of this section, but the cnum values need to De explained: 

0 - player 0 8 - playfield 0 

1 - player 1 9 - playfield 1 

2 - player 2 10 - playfield 2 

3 - player 3 11 - playfield 3 


The playfield numbers 0-3 are the same as those used in the 
SetColor Library routine to set playfield colors. 


j 



Params: Not Applicable. 

Description: By using the statement: PMHitClr*0 you can clear the 
P/M collision registers. You should do this just before you do 
something which might result in a collision (such as PMMove), or you 
may have information from previous collisions still in the registers. 
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Purpose: To Keep tracK of the current horizontal positions of the P/Ms. 


Params: The element number of the array (same as P/M number). 


Description: By accessing an element of this array you can find out the 
current horizontal Position of any P/M. Simply use the P/M number as 
the array element (e.g. PMHPosO) will give the horizontal Position of 
player 3). The values in this array should not be changed by you. 


BY TE ARRAY PMVPos(8) 

Purpose: To Keep tracK of the current vertical positions of the P/Ms. 

Params: The element number of the array (same as P/M number). 

Description: By accessing an element of this array you can find out the 
current vertical Position of any P/M. Simply use the P/M number as 
the array element (e.g. PMVPos(5) will give the vertical Position of 
missile 1). The values in this array should not be changed by you. 


Purpose: To turn off P/M graphics whenever changing bit-map graphics 
modes. 


Params: mode - same as in the Graphics Library routine. 


Description: This procedure simply turns off the P/M graphics every 
time you change bit-map graphics modesi and replaces the normal 
Graphics Library routine. This routine is necessary, for the P/M 
grapmcs memory is allocated just below screen memoryi so changing 
screen modes could wipe out part of the P/M space. If you are changing 
between graphics modes which use the same amount of memory, you can 
comment out this procedure frcm the source listing and so Keep 
Graphics just the way it was. 
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The following two procedures are extensions of the Library PrintF routine, 
and allow you to control field size and justification as well as the type of 
data output. 


The following routines are internal to the PRINTF routines, and should not 
be used by you unless you are sure of their function: 

BYTE FIWC PF.ToLower 
BYTE FUNC PF_IsDigit 
CARD FUNC PF_Nbase 


PROC PrintF(BYTE ARRAY control CARD cl,c?.e3,c4.c5.c6) 


Purpose: To allow formatted output of data. 


Params: control - the string which determines the format of the 
following data. 

d thru cö - the data to be output 


Description: This procedure is an Upgrade to the Print? routine in the 
ACTION! Library. The difference lies in the Controls available and the 
modifcations which can be made to the Controls. The Controls 
themselves are: 


XD - Decimal Notation 

XO - Octal Notation 

XH - Hexadecimal Notation 

XU - Unsigned CARD Notation 

XC - Character 

XS - String (BYTE ARRAY) 

XE - Carriage Return/End-of-Line 
XX - the 'X' character 

So far this looKs very similar to the 'normal' PrintF routine. However, 
the best 15 yet to come. Between the '%' and the control character 
(except '£' and '%') you may insert some field size and justification 
information as follows: 

A minus sign: this indicates left justification of the data within its 
field (right justification is the default). 

A number: determines the minimum field size for the data. The data 
will be printed in a field at least number wide, and wider if the 
data is too long, If the data is shorter than the field size it will 
be right justified in the field unless the '-' modifier has been used. 

A '.' followed by a number: indicates the maximum number of 
characters of data to print into the field. 
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Example: Th* following list of conlrol strings show how the different 
modifiers affect th* printing of th* string “ACTION*" (w* have placed 
broken bar« to Show th« field size): 

y.s i ACTION! ! 

X5S iACT ION! ! 

X10S I ACTION! i 

y.-ies ! ACT ION! I 

•/.1B.4S i ACTI ; 

X-10.4S ;ACTl 

X.4S ACTI 1 


PROC PrintFDtBVTE chan 1 


ARRAY control CARD cl,c2,c3,c4,c5iCiS) 


Purpos«: To allow formatted output of data to a spectfied channel. 


Params: chan - the channel number (8-7) 
control - sam* as PrintF 
cl thru c6 - sarae as PrintF 


Drscription: This procedur* is exactly like the above PrintFi except 
that it allows you to direct the output to a specific channel (device). 
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This file contains routines which allow you to access the ROM floating 
point routines fron ACTION!, thus making the ACTION! language more 
useful when writing numerically oriented programs. 

To use the floating point routines (hereafter called the Real routines), you 
must dedare variables of the type REAL, for example: 

REAL x,y,z 

The type REAL is actually a record type, so the name of the variable is a 
pointer to the record itself. This makes it very similar to an array. 

You cannot use the assignment Statement to assign a value to a real, since 
the ACTION! Compiler does not internally understand reals. You must 
instead use RealAssign, ValR, IntToReal, InputR, or InputRD. 

Also included in this file are some mathematical routines to mar.ipulate 
reals, as well as routines to print out reals. 

Following each routine's description section are some examples of that 
routine's usage. For these examples, assume the following dedarations: 

REAL xreat,yreal,zreal 

BYTE ARRAY astring 

INT xint,yint,zint 

BYTE channel 

The following routines are internal to the ACTION! real routines, and 
should not be used by you: 


PROC 

ROM-AFP 

PROC 

R0M.FASC 

PROC 

R0M-1FP 

PROC 

ROM-FPI 

PROC 

ROM-FSUB 

PROC 

ROM-FADD 

PROC 

ROM-FMULT 

PROC 

ROM-FDIV 

PROC 

ROM-EXP 

PROC 

ROM-EXP10 

PROC 

ROM-LOG 

PROC 

ROM-LOB10 

PROC 

ROM-JNIT 




Note: You will often see the type REAL POINTER in the declaration of the 
Parameters of a routine. This simply means that you should use the name 
(identifier) of the real, since the name alone is a pointer to the real. 



Page 2t 


ACTION! ToolK'it ver ' *0 



Purpose: To put an INT value into a REAL variable. 


Params: i - the INT value to be assigned to the REAL. 

r - the REAL to which the INT value is assigned. 


Description: This procedure allows you to assign the value of an INT 
to a REAL variable. H the ACTION! Compiler could manipulate reals, 
this routine would be the äquivalent of: r*i. 


Examples: 

xint*453 

IntToReallx int ( x real) ixreal now equals 453 
lntToReal!2534,yreal) iyreal now equals 2534 



Purpose: To return the INT value of a REAL variable. 


Params: r - the REAL variable. 


Description: This function will return the INT value of the REAL 
passed to it as a Parameter. 


Examples: 

x int* RealToIntlx real) ;xint now equals the INT value of xreal 


Purpose: To convert a REAL to a string. 


Params: r - the REAL to converi. 

s - the string in which to Store the character representation 
of the REAL. 


Description: This procedure converts a REAL into its character 
representation. 


Examples: 

InToReal(3924ixreal) jxreal * 3924 
StrRtxreal,astring) ;astring now contains “3924“ 
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Purpose: To convert a string to a REAL. 

Params: s - the string to convert. 

r - the REAL to which the value of s will be assigned. 

Description: This procedure will convert as much of the string as 
possible into a REAL variable (i.e.i if the string is "abcde“, this 
routine will put 6 into the REAL). 

Examples: 

astring=“45.274“ 

ValR(astringixreal) ;same as xreal*45.274 
ValR(*2.7E-4",yreal> ;same as yreal*2.7*lB*4 
ValR("70.2agr",zreal);same as zreal*70.2 
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PROC RealAssionlREAL POINTER a,b) 

Purpose: To assign the value of one REAL variable to another. 

Params: a - the REAL value tD assign. 

b - the REAL to which the value a is assigned. 

Description: This procedure allows you to assign the value of one 
REAL to another one. If the ACTION! Compiler could manipulate realst 
the equivalent would be: b*a. 

Examples: 

RealAssign(xrealtyreal) ;same as yreal*xreal 
RealAssign(zrealtyreal) ;same as zreal*yreal 


PROC RealAddlREAL POINTER a.b.c) 


Purpose: To add two REALs 

Params: a - an addend 
b - an addend 
c - the sum 

Description: This procedure allows you to add two REALs. If the 
ACTION! Compiler could manipulate realst this routine would 
equivalent to: c*a+b. 


Examples: 

RealAdd(xrealtyrealtzreal) ;same as zreal*xreal+yreal 
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PROC RealSubiREAL POINTER a.b.c) 

Purpose: To subtract two REAL« 

Params: a - the Subtrahend 
b - the minuend 
c - the difference 

Description: This procedure allows you to subtract two REALs. If the 
ACTION! Compiler could manipulate realsi this routine would 
equtvalent to: c«a-b. 

Examples: 

RealSubixrealiyreal.zreal) ;same as zreal-xreal-yreal 


PROC RealHultfflBAL POINTER a,b,c) 

Purpose: To multiply two REALs 

Params: a - the multplicand 
b - the multiplier 
c - the product 

Description: This procedure allows you to multiply two REAls. If the 
ACTION! Compiler could manipulate reals, this routine would 
equivalent to: c*a*b. 

Examples: 

RealMult(xrealiyrealitreal) ;same as :real=xreal*yreal 


PROC RealDiviREAL POINTER a.b.c) 

Purpose: To divide two REALs 

Params: a - the dividend 
b - th* divisor 
c - the quotient 

Description: This procedure allows you to divide two RBALs. If the 
ACTION! Compiler could manipulate reals ( this rcutine would 
equivalent to: ca/b. 

Examples: 

RealDiv(xrealtyreal)Zreal) ;same as zreal=xreal/yreal 
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PROC ExoIREAL POINTER a.b) 

Purpose: To raise e to the a power. 

Params: a - the power to which to raise e. 

b - the result of raising e to the a power. 

Description: This procedure allows you to get the base e exponential 
of a REAL. The equivalent of this is: b*ea, 

Examples: 

Exp(xrealiyreal) ;yreal=e xr e*l 


Exol6(REAL POINTER a.b) 

Purpose: To raise 10 to the a power. 

Params: a - the power to which to raise 16. 

b - the result of raising 10 to the a power. 

Description: This procedure allows you to compute the base 10 
exponential of a REAL. Its equivalent is: b*16*. 

Examples: 

Expl6(xreal,yreal) ;yreal*10 xre * 1 


PROC PoweriREAL POINTER a.b.c) 

Purpose: To raise a REAL to a REAL power. 

Params: a - the base of the power. 

b - the power to which to raise a. 
c - the result of raising a to the b power. 

Description: This routine allows you to raise one REAL to a power 
specified by another REALi and is equivalent to: c^ab^ 

Examples: 

Power(xreal,yreal,zreal) ;zreal*xreaiy r **l 
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PRQC LnfRBAL POINTER a.b) 

Purpos*: To take th* natural logarithm of a REAL. 

Params: a - th* REAL whose natural log is taKen. 

b - th* result of taking the natural log of a. 

Description: Thic proccdure allows you to taKe the natural (base e) 
logarithm of a REAL, and is äquivalent to: b*)n(a). 

Bxamples: 

Ln(xreal.yreal) ;yr*al*ln(xreal) 

PRQC Lool0(REAL POINTER a.b) 

Purpose: To take the common (base 10) logarithm of a REAL. 

Params: a - the REAL whos* common log is taken. 

b - the result of taking the common log of a. 

Description: This proccdure allows you to take the ccmmon (base 10) 
logarithm of a REAL, ard is equivalent to: b 3 log(a). 

Bxamples: 

Logl0(xreal.yreal) ;yreal=log(xr*al) 

I/O Routines 
PRQC PrintR(REAL POINTER a) 

Purpose: To output a REAL to the default device. 

Params: a - the REAL to be output. 

Description: This proccdure Outputs a real number to the default 
device without a RETURN. 

PRQC PrintRDtBVTS channel REAL POINTER a) 

Purpose: To output a REAL to a specified channel (device). 

Params: channel - the output channel 
a - the REAL to be output. 

Description: This proccdure Outputs a real number to the device 
specified by channel without a RETURN. 
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PRQC PrintREIREAL POINTER a) 

Purpos*: To output a REAL to th* default device with a RETURN. 
Params: a - the REAL to be output. 

Description: This procedure Outputs a real number to the default 
device with a RETURN. 

PRQC PrintRDEtBYTE channel REAL POINTER a) 

Purpose: To output a REAL to a specified channel (device) with a 
RETURN. 

Params: channel - the output channel. 
a - the REAL to be output. 

Description: This procedure Outputs a real number to the specified 
device with a RETURN. 

PRQC InoutRtRBAL POINTER a) 

Purpose: To input a REAL from the default device. 

Params: a - the REAL variable in which to störe the input value. 

Description: This procedure inputs a real number from the default 
device and stores it in the specified REAL variable. 

PRQC lnoutRD(BYTE channel REAL POINTER a) 

Purpose: To input a REAL from a specified channel (device). 

Params: channel - the input channel. 

a - the REAL variable in which to störe the input value. 

Description: This procedure inputs a real number from the specified 
device and stores it in the given REAL variable. 
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The following four sort routines all usf the QuickSort algorithm. This 
algorithm was used because it is very fast (order N log N). ln th« best 
case QuicKSort is. in facti among the fastest sorting algorithms known. 
For comparisoni both the Bubble and the Shell algorithms are of order N2. 
The QuicKSort can deteriorate to this speed when sorting presorted data. 

If you take a look at the SORT.ACT source you will see that you can create 
your own routines to sort REALs or complex record TYPEs simply by 
writing your own Compare and Swap routines. 

Usage Note: Before using any of these routines you should first change 
the source line which reads 

DEFINE SortMax="10008" 

to the maximum size of the data array you expect to encounter. An 
alternative is to change the sort routines so that they 
INCLUDE ALLOC.ACT and dynamically create the 'List' array. 




Purpose: To sort one-byte data in either ascending or descending 
order. 


Params: data - the array containing the data to be sorted. 
len - the length of the data array. 

order - determines order of sort <0=ascending, 1-descending) 

Description: This procedure allows you to sort one-byte data very 
quickly. 



Purpose: To sort two-byte unsigned data in either ascending or 
descending order. 


Params: data - the array containing the data to be sorted. 
len - the length of the data array. 

order - determines order of sort (0 s ascendingi l*descending) 

Description: This procedure allows you to sort two-byte unsigned data 
very quickly. 
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Purpose: To sort two-byte signed data in either ascending or 
descending order. 


Params: data - the array containing the data to be sorted. 
len - the length of the data array. 

order - determines order of sort (0>ascending, l*descending) 

Description: This procedure allows you to sort two-byte signed data 
very quickly. 



Purpose: To sort string data in either ascending or descending order. 


Params: data - the array containing the addresses of the strings to 
be sorted. 

len - the length of the data array. 

order - determines order of sort <0*ascending> 1-descending) 


Description: This procedure allows you to sort strings very quickly. 
Notice that the addresses of the strings to be sorted must be the 
elements of the CARD ARRAY data. 
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TURTLE .ACT 

The routines in this file implement turtle graphics ala LOGO. 

These routines require that the screen be in a bit-map graphics mode in 
which Plot and OrawTo are useable. Also» the length of a line drawn 
depends on the graphics mode» and there is no screen bounds checking. 

Also» the color of the line drawn by the turtle depends entirely upon then 
current value of the System variable color» so you should use SetColor and 
color to choose the color you want. 

The following routines are internal to the turtle graphics and should not 
be called by you 

CARD FUNC TG_ISin CARD FUNC TG-lCos 


PROC RiahtONT theta) 

Purpose: To turn the turtle right (dockwise) theta degrees. 

Params: theta - the angle to turn the turtle dockwise. 

Description: This procedure allows you to turn the turtle dockwise a 
specified number of degrees. 


PROC Left (INT theta) 

Purpose: To turn the turtle left (counterdockwise) theta degrees. 

Params: theta - the angle to turn the turtle counterdockwise. 

Description: This procedure allows you to turn the turtle counter¬ 
dockwise a specified number of degrees. 


PROC TurnüMT theta) 

Purpose: To turn the turtle either dockwise or counterdockwise. 
Params: theta - the angle to turn the turtle. 

Description: This routine allows you to turn the turtle either 
dockwise or counterdockwise» depending on the sign of the angle. If 
theta is positive» the turtle will turn counterdockwise» otherwise it 
will turn dockwise. 


PROC ForwarddKT lenoth) 

Purpose: To move the turtle forward a specified length. 

Params: length - the length to move forward. 

Description: This procedure allows you to move the turtle forward a 
specified length. This length depends entirely upon the current 
graphics mode. 


PROC SetTurtledNT x.y.theta) 

Purpose: To move the turtle to a specified x,y Position at a given 
angle. 

Params: x - the horizontal Position at which to set the turtle, 
y - the vertical Position at which to set the turtle, 
theta - the angle at which to set the turtle. 

Description: This procedure allows you to move the turtle tD an 
absolute x»y Position and point it in a specific direction. At theta*0° 
the turtle points right, at 98° it points up, at 1800 it points left» and 
at 2700 it points down. In essence» increasing positive values of 
theta turn the turtle counterdockwise, and increasing negative 
theta values turn it dockwise. 
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OE M .DE M 

Gern is a game which was written by Joel Gluck after having the 
ACTION! cartridge for only 2 days. If you look at the codei you will notice 
how similar it is to BASIC. This reflects Joel's previous programming 
experienct (BASIC only) and is not due to lts being originally written in 
BASIC (which it was not). Enough of its history. Gern is designed for 1 to 
4 players, »ach using a Joystick. The object is to steal the gern in the 
center of the screen and return to your home base before one of the robots 
or other players zaps you. However, betöre the game ltself begins, you 
are prompted for some Information, specifically: 

How many points to win the game? 

How many robots in the final round? 

Winning Points - to win a point, you must get the Gern and return with it to 
your Corner. 

Robots - the number of robots increase each round. Although they seem to 
die off, whenever the gern is picked up they all come back. If one of the 
robots is destroyed while one of the players is carrying the gern, it is 
reincarnated immediately. 

Zapping - to zap a robot or another player, press the joystick trigger while 
pointing the Joystick in the direction of the target. While you are zapping 
you cannot move. You can also zap by running into the target, but this 
also zaps you, so only uce this method when on a Kamikaze run to keep 
another player from getting the gern home. 

Getting Zapped - when you get zapped, you are reincarnated back at your 
home base and the gern is taken from you if you are carrying it. There is 
no limit to the number of times you can be reincarnated. 

Winning - when one of the players has accumulated the required number of 
points, he wins the game, and you may either play again, or quit and go to 
the ACTION! monitor. 

Technical Notes - to us» this game, do not read it into the ACTION! Editor 
and then compile it, since there is not enough memory to do both. Instead, 
RUN it from the ACTION! Honitor directly from disk. (This note does not 
apply if you are using DOS XI, since you have more memory and can have 
the game in the Editor while compiling it). 

The maximum recommended number of robots is 100. Bugs will appear in 
the program if you use many more, but do not fret. The most robots 
survived to date is 43 in a one player game. 


K'ALSCOPE .DE M 

This demo program uses advanced math and display list algorithms to 
achieve the effect of a kaleidoscope on your TV. When you run it you will 
be amazed by its speed. You can even change the kaleidoscope's speed and 
persistence (amount of tut.e a point remains on the screen) by moving 
Joystick 0 vertically or honzontally, respectively. After playing with it a 
while you will be surprised by the number and variety of the different 
patterns it can create. 

P.S. - you can freeze the picture by pressing the trigger. 


MUSI C.DE M 

This demo program uses a couple of the Toolkit Utilities and kncwledge of 
the Atari's keyboard matrix to produce an organ which will play as you 
press the keys. ■ , ^ 

The letters on the keyboard represent the notes, and the letters above and 
below the keyboard represent the actual Computer keys you must press to 
get the note. By pressing <SHIFT><note> you can access the middle 
octave, and by pressing <CONTROLXnote> you can access the high octave. 

This organ is special (for Atari's) in that it only plays a note as lüng as 
you keep the Key depressed. Few people Know how to determine how long a 
Key is pressed (unless they've deciphered the Type-a-Tune demo in the 
BASIC reference manual, or waded through the hardware manual), so if you 
look at the source Code you can discover something useful (possibly). 
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SNAILS.DE m 

Games similar to "SNA1LS' TRAILS" have been around for a long time. A 
Version called "SURROUND" was one of the first games available for the 
Atari 2600. Suti in the tradition of the Video game industry, we present a 
storyline: 

You ar* a giant. mutant snail. Wherever you traveli you leave a trail of 
radioactive slime behind. So poisonous and impenetrable is this slime that 
should any being (induding you yourself) touch it, it dies instantly. (Yes, 
yes. If it's that poisonousi how could you lay the trail in the first place? 
How should we know...YOU are the mutant.) 

Further, the scientists of far off H'tra-E have discovered your Kind and 
have impnsioned you and another of your race in a large rectangular arena. 
Unfortunatelyi both of you are neither male or female. Instead, you are 
each a St'i, specially bred to do battle until death! You don't Know the 
meaning of the word “STOP". 

SOi as the scientists release you from stasis (you hear three bells as the 
stasis field is lifted), you begin by charging straight toward your 
Opponent. But wait! A bit of intellingence enters your cra 2 ed brain. Jf 
your slime trail is so deadly, perhaps you can entice your enemy to run 
into it, thus killing the other S'ti without damage to yourself. Great 
strategy! 

What's this, though? Your Opponent has developed the same strategy. 
Now you and the other S'ti must race around the arena, with the Strategie 
goal of forcing each other to touch a poisonous trail or to run into the 
electrified outer fence. (Well, we had to Keep you in the arena somehow, 
didn't we?) But tactics can oe important as well. Look, you are runmng 
straight across the arena. At the last second, you veer in front of your 
enemy! He can't avoid your trail in time! He's going to...Oops. You forgot 
about the wall. Too bad. R.l.P. 

To mak* a long story into a short game, you and another human Opponent 
must each use a Joystick (plugged into ports 1 and 2) to control your snail. 
The first snail to run into a slime trail or a wall loses, and the other snail 
scores a point. The first snail to score 10 points wins the game. Also, if 
both snails die at the same instant, neither scores a point. Good Luck! 

P.S. This game was converted from BASIC XL to ACTION! in about two 
hours. The original BASIC XL Version is in Chapter 29 of Thirty Dave to 
Understandino BASIC XL and is on the BASIC XL ToolKit diskette. 
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warp.de m 

Warp Attack is a game for only the most daring interstellar pilots. You 
have been chosen as one of tnis special breed and are sent on a surface 
patrol over the planet Stripes. You can move you ship left or right and you 
can dive or climb as in an airplane, but your on-board navigational 
equipment won't allow you to crash into the planet surface. As you are 
flying along minding your own business, an Hospites (your sworn enemy) 
Stellar Fortress warps right into your path, and she's armed to the teeth 
with Seeker PlasmaBalls. One touch of them and you're dust. And all you 
have are puny pulse cannons. 

Now you know why only the best were chosen for this assignment: very few 
know how to destroy a Stellar Fortress, and you are one of them. You 
first must destroy its right erigine (on your left as it approaches). then lts 
left engine, and finally its main engine, and each must be a direct hit. 
While completing this feat of precision marksmanship you must rememter 
to avoid those PlasmaBalls. Piece of Cake! 

Technical Notes: Warp Attack uses quite a few advanced programming 
techniques, including a modified display list, display list Interrupts, 
vertical blank interrupts, and a block fastdraw. The DLI and VB! together 
create the scrolling planet surface, and the fastdraw is used to move the 
Stellar Fortress (it's not a player!). 


